/*
 * Package il.ac.biu.cs.grossmm.impl.server
 * File Server.java
 * 
 * This is a part of presence service framework API. 
 * See javadoc for more information.
 *  
 * Copyright (C) 2006 Grossmann Mark
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */
package il.ac.biu.cs.grossmm.api.server;

/**
 * Represents a server which can be started and stopped. Unlike a service which
 * can be started or stopped by a server framework, the server is manipulated by
 * user objects.
 */
public interface Server {
	/**
	 * Instances of this class represent server states. There are exactly 
	 * four server states:
	 * <ul>
	 * <li> NOT_RUNNING - server is not running
	 * <li> STARTING - server is starting up
	 * <li> RUNNING - server is  running
	 * <li> STOPPING - server is shutting down
	 * </ul
	 */
	final class ServerState {
		String s;

		protected ServerState(String s)
		{
			this.s = s;
		}

		@Override
		public String toString()
		{
			return s;
		}
	}

	/**
	 * Represents a server state when server is not running
	 */
	ServerState NOT_RUNNING = new ServerState("Not running");

	/**
	 * Represents a server state when server is starting up
	 */
	ServerState STARTING = new ServerState("Starting");

	/**
	 * Represents a server state when server is running
	 */
	ServerState RUNNING = new ServerState("Running");

	/**
	 * Represents a server state when server is shutting down
	 */
	ServerState STOPPING = new ServerState("Stopping");

	/**
	 * Starts the server. The method returns when the server is completely 
	 * started (i.e. is in a running state).
	 * @throws Exception in case the server could not start
	 */
	void start() throws Exception;

	/**
	 * Stops the server. This method returns when the server is complitely shut
	 * down (i.e. is in a not-running state).
	 * 
	 */
	void stop();

	/**
	 * Stops the server due to an exceptional situation
	 * @param exception describes the exceptional situation
	 */
	void stop(Exception exception);

	/**
	 * Gets the current server state
	 * @return the current server state
	 */
	ServerState getState();

}
